// Copyright (c) Microsoft Corporation.  All rights reserved.

using System;
using System.Collections.Generic;
using System.IO;

namespace Microsoft.WindowsAPICodePack.Shell
{
    /// <summary>
    /// Represents a registered or known folder in the system.
    /// </summary>
    [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1710:IdentifiersShouldHaveCorrectSuffix", Justification="This will complicate the class hierarchy and naming convention used in the Shell area")]
    public interface IKnownFolder : IDisposable, IEnumerable<ShellObject>
    {
        /// <summary>
        /// Gets the path for this known folder.
        /// </summary>
        string Path
        {
            get;
        }

        /// <summary>
        /// Gets the category designation for this known folder.
        /// </summary>
        FolderCategory Category
        {
            get;
        }

        /// <summary>
        /// Gets this known folder's canonical name.
        /// </summary>
        string CanonicalName
        {
            get;
        }

        /// <summary>
        /// Gets this known folder's description.
        /// </summary>
        string Description
        {
            get;
        }

        /// <summary>
        /// Gets the unique identifier for this known folder's parent folder.
        /// </summary>
        Guid ParentId
        {
            get;
        }

        /// <summary>
        /// Gets this known folder's relative path.
        /// </summary>
        string RelativePath
        {
            get;
        }

        /// <summary>
        /// Gets this known folder's parsing name.
        /// </summary>
        string ParsingName
        {
            get;
        }

        /// <summary>
        /// Gets this known folder's tool tip text.
        /// </summary>
        string Tooltip
        {
            get;
        }

        /// <summary>
        /// Gets the resource identifier for this 
        /// known folder's tool tip text.
        /// </summary>
        string TooltipResourceId
        {
            get;
        }

        /// <summary>
        /// Gets this known folder's localized name.
        /// </summary>
        string LocalizedName
        {
            get;
        }

        /// <summary>
        /// Gets the resource identifier for this 
        /// known folder's localized name.
        /// </summary>
        string LocalizedNameResourceId
        {
            get;
        }

        /// <summary>
        /// Gets this known folder's security attributes.
        /// </summary>
        string Security
        {
            get;
        }

        /// <summary>
        /// Gets this known folder's file attributes, 
        /// such as "read-only".
        /// </summary>
        FileAttributes FileAttributes
        {
            get;
        }

        /// <summary>
        /// Gets an value that describes this known folder's behaviors.
        /// </summary>
        DefinitionOptions DefinitionOptions
        {
            get;
        }

        /// <summary>
        /// Gets the unique identifier for this known folder's type.
        /// </summary>
        Guid FolderTypeId
        {
            get;
        }

        /// <summary>
        /// Gets a string representation of this known folder's type.
        /// </summary>
        string FolderType
        {
            get;
        }
        
        /// <summary>
        /// Gets the unique identifier for this known folder.
        /// </summary>
        Guid FolderId
        {
            get;
        }

        /// <summary>
        /// Gets a value that indicates whether this known folder's path exists on the computer. 
        /// </summary>
        /// <remarks>If this property value is <b>false</b>, 
        /// the folder might be a virtual folder (<see cref="Category"/> property will
        /// be <see cref="FolderCategory.Virtual"/> for virtual folders)</remarks>
        bool PathExists
        {
            get;
        }

        /// <summary>
        /// Gets a value that states whether this known folder 
        /// can have its path set to a new value, 
        /// including any restrictions on the redirection.
        /// </summary>
        RedirectionCapabilities Redirection
        {
            get;
        }
    }
}
